home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / basic / RIBlitzLibs.lha / riblitzlibs / docs / RIAmosFuncLib.doc < prev    next >
Encoding:
Text File  |  1995-01-30  |  16.5 KB  |  621 lines
  1. -----------------------------------------------------------------------------
  2. ====                 RI AMOS Function Library V1.36 (C)1995         ====
  3. -----------------------------------------------------------------------------
  4.  
  5.                           Written By Steven Matty
  6.                         ©1995 Leading Edge Software
  7.  
  8.   This library was written primarily to emulate the functions that were
  9. present in AM*S but not in Blitz Basic 2. It began life as a load of Blitz
  10. Statements but was then converted to high speed 680x0. The library will
  11. continually be expanded upon. 
  12.  
  13. Donations are not requested, but is always welcome. You may freely
  14. distribute this library as long as all documentation is included in an
  15. unmodified form. *NO* distribution with commercial packages/magazines
  16. without express written permission.
  17.  
  18.  
  19. Command List:
  20.  
  21.     success=Reserve(length) | (banknumber,length)
  22.     success=SwapBank(bank,bank)
  23.     Erase(banknumber)
  24.     EraseAll
  25.     address.l=Start(banknumber)
  26.     length.l=Length(banknumber)
  27.     success=BLoad(filename$) | (banknumber/address[,length,offset])
  28.     success=BSave(filename$,banknumber/address,length)
  29.     success=PLoad(filename$,banknumber/address)
  30.     bytes.l=FileSize(filename$)
  31.     banknumber=NextBank
  32.     bytes.l=MemFree
  33.     value.l=Max(value1.l,value2.l)
  34.     value.l=Min(value1.l,value2.l)
  35.     value.l=XOR(value1.l,value2.l)
  36.     id.w=Lisa
  37.     Reboot
  38.     code.b=KeyCode
  39.     CopyByte sourceaddress.l,destaddress.l,numbytes.l
  40.     CopyWord sourceaddress.l,destaddress.l,numwords.l
  41.     CopyLong sourceaddress.l,destaddress.l,numlongs.l
  42.     FillMem sourceaddress.l,numberbytes.l[,bytevalue.l]
  43.     CachesOff bitmask
  44.     CachesOn  bitmask
  45.     number.l=Timer
  46.     ResetTimer
  47.     success=Rename(source$,dest$)
  48.     success=MakeDir(dirname$)
  49.     tagnumber.l=GTTagValue[(tagnumber)]
  50.     success=CludgeShapes(shapenum#,numshapes,address)
  51.     success=CludgeSound(soundnumber,address)
  52.     success=FindVolume(volumename$)
  53.     status=BlitterDone
  54.     WaitBlitter
  55.     devicename$=DeviceName$(volumename$)
  56.     BlitterNasty On|Off
  57.     FuncLibVersion
  58.  
  59.  
  60. ************ NOTE ****************
  61. * AS FROM THIS VERSION (V1.36)   *
  62. * THERE WILL BE NO MORE COMMANDS *
  63. * ADDED. INSTEAD, A NEW LIBRARY  *
  64. * CALLED RIAMOSPROFUNC WILL BE   *
  65. * RELEASED. THIS IS DUE TO LARGE *
  66. * LIBRARY SIZE AND THE FACT THAT *
  67. * BLITZ V1.90 DOES NOT INCLUDE   *
  68. * A LINKER.                      *
  69. **********************************
  70.  
  71.  
  72. ********************************* NOTE **************************************
  73. * VALID BANKS RANGE FROM 0-49 INCLUSIVE. DO NOT USE A VALUE GREATER THAN 49 *
  74. * OR IT WILL BE INTERPRETED AS AN ADDRESS RATHER THAN A BANKNUMBER          *
  75. *****************************************************************************
  76.  
  77.  
  78.                           MEMORY AND FILE ACCESS
  79.                           ======================
  80.  
  81. Function: Reserve
  82. --------------------------------------------------------------------------------
  83. Mode   : Amiga/Blitz
  84. Syntax : success=Reserve(length) | (banknumber,length[,requirements])
  85.  
  86.   If only length if specified, then this functions returns the number of the
  87.   bank allocated or -1 for failure.
  88.  
  89.   This will attempt to reserve <length> bytes of memory. If succesfull,
  90. it will return -1. If unsuccessfull, 0 is returned.
  91.  
  92. The optional <requirements> parameter specifies which type of memory you
  93. want :        
  94.         %1=PUBLIC
  95.         %10=CHIP 
  96.         %100=FAST
  97.         %100000000=LOCAL
  98.         %1000000000=24BITDMA
  99.         %10000000000=KICK
  100.         %10000000000000000=CLEAR
  101.         %1000000000000000000=REVERSE
  102.         %10000000000000000000000000000000=NO_EXPUNGE
  103.  
  104. OR the values together for different combinations.
  105.  
  106. EXAMPLE:
  107.     suc=Reserve(0,1024,%10)        ; Reserve 1k of Chip Mem returns -1
  108.     suc=Reserve(1024)        ; Reserve 1k of Any Mem returns 1
  109.  
  110. Statement: Erase
  111. --------------------------------------------------------------------------------
  112. Mode   : Amiga/Blitz
  113. Syntax : Erase banknumber
  114.  
  115.   The Erase command will erase the specified memory bank.
  116.  
  117. EXAMPLE:
  118.     suc=Reserve(0,1024,%10)        ; Reserve 1k of Chip Mem
  119.     Erase 0
  120.  
  121.  
  122. Statement: EraseAll
  123. --------------------------------------------------------------------------------
  124. Mode   : Amiga/Blitz
  125. Syntax : EraseAll
  126.  
  127.   This command will erase ALL allocated memory banks.
  128.  
  129. EXAMPLE:
  130.     suc=Reserve(0,1024,%10)        ; Reserve 1k of Chip Mem
  131.     suc=Reserve(1,2048,0)        ; Reserve 1k of ANY Mem
  132.     EraseAll
  133.  
  134. Function: BLoad
  135. --------------------------------------------------------------------------------
  136. Mode   : Amiga
  137. Syntax : success=BLoad(filename$) | (filename$,bank/addr[,length,offset,memtype])
  138.  
  139.   If only filename$ is specified, then the next available bank is allocated,
  140.   and the command returns the number of the bank for success or -1 for failure.
  141.  
  142.   If bank is specified, then the file is loaded into that bank. If address
  143. is specified then it is loaded to the address. Valid banks are 0-49. 
  144. If the bank does not exist, Blitz will reserve a bank for you.
  145. If the bank does exist, Blitz will erase the bank from memory, and
  146. allocate a new one.
  147. The return result is -1 for success, or 0 for failure  (not enough RAM, 
  148. file not exist). If offset is specified, then <length> bytes will be read
  149. from the specified offset position in the file.
  150. If memtype is specified, then the file is loaded into a memory block
  151. of that particular memtype (see Reserve)
  152. If you wish to leave either length/offset unspecified, simply use the
  153. value 0
  154.  
  155. EXAMPLE:
  156.     suc=BLoad("s:startup-sequence",0)    ; returns -1
  157.     suc=BLoad("c:dir",0,0,0,%10)        ; Loads into CHIP
  158.     suc=BLoad("c:list")            ; returns 1
  159.  
  160. Function: PLoad
  161. -------------------------------------------------------------------------------
  162. Mode   : Amiga
  163. Syntax : success=PLoad(filename$,bank/address)
  164.  
  165.   This will attempt to load the executable file to the specified address.
  166.   -1 is success, 0 is failure. The program must contain only a CODE
  167. hunk and must be FULLY relocatable.
  168.  
  169. EXAMPLE:
  170.  
  171.     suc=PLoad("c:dir",0)
  172.  
  173.  
  174. Function: BSave
  175. --------------------------------------------------------------------------------
  176. Mode   : Amiga
  177. Syntax : success=BSave(filename$,bank/address,length)
  178.  
  179.   This will save <length> bytes at bank/address to the file. Return result
  180. is -1 for success, 0 for failure. If length > bank length then the length
  181. of the bank is saved instead. If 0 is specified, the entire bank is saved.
  182.  
  183. EXAMPLE:
  184.     suc=BLoad("c:dir",0,0,0,%10)        ; Loads into CHIP
  185.     suc=BSave("ram:temp",0)
  186.  
  187.  
  188. Function: Start
  189. -------------------------------------------------------------------------------
  190. Mode   : Amiga/Blitz
  191. Syntax : start_address.l=Start(banknumber.b)
  192.  
  193.   This will return the start address of the specified bank. (0=no bank)
  194.  
  195. EXAMPLE:
  196.     suc=Reserve(0,1024,%10)
  197.     NPrint Start(0)
  198.     MouseWait
  199.     End
  200.  
  201.  
  202. Function: Length
  203. -------------------------------------------------------------------------------
  204. Mode   : Amiga/Blitz
  205. Syntax : length_of_bank.l=Length(banknumber.b)
  206.  
  207.   This will return the length of the specified bank in bytes. (0=No bank)
  208.  
  209. EXAMPLE:
  210.     suc=Reserve(0,1024,%10)
  211.     NPrint Length(0)
  212.     MouseWait
  213.     End
  214.  
  215.  
  216. Function: MemFree
  217. --------------------------------------------------------------------------------
  218. Mode   : Amiga/Blitz
  219. Syntax : bytes.l=MemFree
  220.  
  221.   This will return the total amount of Public Free RAM available to the
  222. system.
  223.  
  224. EXAMPLE:
  225.     NPrint "Total bytes free = ",MemFree
  226.     MouseWait
  227.     End
  228.  
  229.  
  230. Function: NextBank
  231. --------------------------------------------------------------------------------
  232. Mode   : Amiga/Blitz
  233. Syntax : bank.b=NextBank
  234.  
  235.   This will return the number of the first available bank (-1 if none free).
  236.  
  237. EXAMPLE:
  238.     suc=Reserve(0,1024)
  239.     suc=Reserve(0,2048)
  240.     NPrint NextBank
  241.     MouseWait
  242.     End
  243.     
  244.  
  245. Statement: FillMem
  246. -------------------------------------------------------------------------------
  247. Mode   : Amiga/Blitz
  248. Syntax : FillMem address.l,length.l[,value.b]
  249.  
  250.    This will fill 'length' bytes starting from the specified address with
  251.    'value'. If 'value' is ommitted, 0 is filled.
  252.  
  253. EXAMPLE:
  254.     suc=Reserve(0,1024)        ; Allocate some memory
  255.     FillMem Start(0),Length(0)    ; Clear it
  256.     MouseWait
  257.     End
  258.  
  259.  
  260. Statement: CopyByte
  261. --------------------------------------------------------------------------------
  262. Mode   : Amiga/Blitz
  263. Syntax : CopyByte source.l,dest.l,num.l
  264.  
  265.   This will copy <num> bytes from <source> to <dest>
  266.  
  267. EXAMPLE:
  268.     CopyByte Start(0),Start(1),Length(0)
  269.  
  270.  
  271. Statement: CopyWord
  272. --------------------------------------------------------------------------------
  273. Mode   : Amiga/Blitz
  274. Syntax : CopyByte source.l,dest.l,num.l
  275.  
  276.   This will copy <num> words from <source> to <dest> 
  277.  
  278. EXAMPLE:
  279.     CopyWord Start(0),Start(1),Length(0)/2
  280.  
  281.  
  282. Statement: CopyLong
  283. --------------------------------------------------------------------------------
  284. Mode   : Amiga/Blitz
  285. Syntax : CopyByte source.l,dest.l,num.l
  286.  
  287.   This will copy <num> longwords from <source> to <dest> 
  288.  
  289. EXAMPLE:
  290.     CopyLong Start(0),Start(1),Length(0)/4
  291.  
  292.  
  293. Function: MakeDir
  294. --------------------------------------------------------------------------------
  295. Mode   : Amiga
  296. Syntax : success=MakeDir(name$)
  297.  
  298.    This function attempts to create a directory called <name$>
  299.    If it is unsuccessfull, 0 is returned else -1 is returned.
  300.  
  301. EXAMPLE:
  302.     suc=MakeDir("RAM:MYDIR")
  303.  
  304.  
  305. Function: Rename
  306. --------------------------------------------------------------------------------
  307. Mode   : Amiga
  308. Syntax : success=Rename(source$,dest$)
  309.  
  310.    This attempts to rename the file <source$> to <dest$>
  311.    NOTE: It is not possible to rename across devices.
  312.    -1 is returned if successfull, else 0.
  313.  
  314. EXAMPLE:
  315.     suc=Rename("S:Startup-Sequence","S:Startup2")    ; Do not run this!
  316.  
  317.  
  318. Function: Timer
  319. --------------------------------------------------------------------------------
  320. Mode   : Amiga/Blitz
  321. Syntax : t.l=Timer
  322.  
  323.    This will return the number of 50ths of a second since startup or the
  324.    last call to ResetTimer.
  325.  
  326. EXAMPLE:
  327.     NPrint Timer
  328.     VWait
  329.     NPrint Timer
  330.     MouseWait
  331.     End
  332.  
  333.  
  334. Statement: ResetTimer
  335. --------------------------------------------------------------------------------
  336. Mode   : Amiga/Blitz
  337. Syntax : ResetTimer
  338.  
  339.    This will recent the CIA timer to 0.
  340.  
  341. EXAMPLE:
  342.     NPrint Timer
  343.     VWait
  344.     ResetTimer
  345.     NPrint Timer
  346.     MouseWait
  347.     End
  348.  
  349.  
  350. Function: Lisa
  351. --------------------------------------------------------------------------------
  352. Mode   : Amiga/Blitz
  353. Syntax : chipver=Lisa
  354.  
  355.    This will return the current Lisa chip version :
  356.  
  357.     $00 for OCS Denise
  358.     $F7 for ECS Denise
  359.     $F8 for AGA Lisa
  360.  
  361. EXAMPLE:
  362.     Select Lisa
  363.       Case 0
  364.         NPrint "You have an OCS Machine!"
  365.       Case $F7
  366.         NPrint "You have an ECS Machine!"
  367.       Case $F8
  368.         NPrint "You have an AGA Machine!"
  369.       Case $F9
  370.         NPrint "You have a AAA Machine?!"    ; Maybe... :)
  371.     End Select
  372.     MouseWait
  373.     End
  374.  
  375.  
  376. Statement: Reboot
  377. --------------------------------------------------------------------------------
  378. Mode   : Amiga/Blitz
  379. Syntax : Reboot
  380.  
  381.    This will perform a cold reboot
  382.  
  383. EXAMPLE:
  384.     NPrint "Press mousebutton to reset.."
  385.     MouseWait
  386.     Reboot
  387.  
  388.  
  389. Function: FileSize
  390. --------------------------------------------------------------------------------
  391. Mode   : Amiga
  392. Syntax : size.l=FileSize(filename$)
  393.  
  394.   This return the length (in bytes) of the file.
  395.  
  396. EXAMPLE:
  397.     NPrint "Startup is ",FileSize("S:startup-sequence")," bytes long!"
  398.     MouseWait
  399.     End
  400.  
  401.  
  402. Function: XOR
  403. --------------------------------------------------------------------------------
  404. Mode   : Amiga/Blitz
  405. Syntax : x.l=XOR(x.l,y.l)
  406.  
  407.   This will perform an Exclusive-Or operation between X and Y and put the
  408. result back into X 
  409.  
  410. EXAMPLE:
  411.     x=XOR(%101,%100)
  412.  
  413. Will place %001 into X (%101 XOR %100 = %001)
  414.  
  415.  
  416. Function: Max/Min
  417. -------------------------------------------------------------------------------
  418. Mode   : Amiga/Blitz
  419. Syntax : value=Max(first_var,second_var)
  420.          value=Min(first_var,second_var)
  421.  
  422.   This will compare both values and return either the Higher of the values
  423.   (Max) or the Lower (Min). This currently supports INTEGERs only.
  424.  
  425. EXAMPLE:
  426.     NPrint Max(30,50)
  427.     NPrint Min(30,50)
  428.     MouseWait
  429.     End
  430.  
  431.  
  432. Function: KeyCode
  433. -------------------------------------------------------------------------------
  434. Mode   : Amiga/Blitz
  435. Syntax : keycode=KeyCode
  436.  
  437.     This will return the status of the keyboard in the form of a keycode.
  438.     You will need to experiment to find out the desired keycode for
  439.     a particular key.
  440.     This merely peeks address $bfec01 and returns the value found.
  441.  
  442. EXAMPLE:
  443.     NPrint KeyCode
  444.     MouseWait
  445.     End
  446.  
  447.  
  448. Statement/Function : CludgeShapes
  449. -------------------------------------------------------------------------------
  450. Mode   : Amiga/Blitz
  451. Syntax : [success]=CludgeShapes(shape#,numshapes,address)
  452.  
  453.    This allows the creation of shapes through INCBIN statements. It
  454. allocates chip memory for each shape and copies the data into this.
  455. It does the same as LoadShapes except it grabs shapes from memory.
  456.  
  457. EXAMPLE:
  458.     suc=BLoad("myshapes",0)
  459.     suc=CludgeShapes(0,50,Start(0))
  460.     MouseWait
  461.     End
  462.  
  463.  
  464. Statement/Function : CludgeSound
  465. ------------------------------------------------------------------------------
  466. Mode   : Amiga/Blitz
  467. Syntax : [success]=CludgeSound(sound#,address)
  468.  
  469.   This does the same for CludgeShapes but works on only 1 sound at a time
  470. NOTE: Looped sounds are not currently supported! The sound must be a valid
  471. 8SVX sample.
  472.  
  473. EXAMPLE:
  474.     suc=BLoad("mysound",0)
  475.     suc=CludgeSound(0,Start(0))
  476.     MouseWait
  477.     End
  478.  
  479.  
  480. Function : FindVolume
  481. ------------------------------------------------------------------------------
  482. Mode   : Amiga
  483. Syntax : success=FindVolume(volumename$)
  484.  
  485.   This will look to see if the specified volume is present, and returns
  486. 0 if it is not or -1 if it is. If the volume is not present, this function
  487. will NOT bring up a Requester ("Please insert Volume...")
  488. The ":" should not be included in the volumename.
  489.  
  490. This is useful for waiting for diskswaps when you have a BlitzMode display
  491.  
  492. EXAMPLE:
  493.         <Blitzmode Statements>
  494.         QAMIGA
  495.         Repeat
  496.           VWait
  497.         Until FindVolume("DISK2")
  498.         BLITZ
  499.         <More statements>
  500.  
  501.  
  502. Function : DeviceName$
  503. ------------------------------------------------------------------------------
  504. Mode   : Amiga
  505. Syntax : devname$=DeviceName$(volumename$)
  506.  
  507.   This will return the device name of the specified volume or "" if the
  508. volume was not found. The ":" may or may not be included.
  509.  
  510. EXAMPLE:
  511.         NPrint DeviceName$("WORK:")
  512.  
  513.  
  514. Function : BlitterDone
  515. ------------------------------------------------------------------------------
  516. Mode   : Amiga/Blitz
  517. Syntax : status=BlitterDone
  518.  
  519.   This checks to see if the Blitter has finished BLITting. -1=Yes, 0=No
  520.  
  521. EXAMPLE:
  522.     Repeat
  523.     Unti BlitterDone
  524.  
  525. Statement : WaitBlitter
  526. ------------------------------------------------------------------------------
  527. Mode   : Amiga/Blitz
  528. Syntax : WaitBlitter
  529.  
  530.   This will halt program execution until the Blitter is ready for use.
  531.  
  532. EXAMPLE:
  533.     Blit 0,0,0
  534.     WaitBlitter
  535.        ..
  536.        ..
  537.  
  538.  
  539. Statement : BlitterNasty
  540. ------------------------------------------------------------------------------
  541. Mode   : Amiga/Blitz
  542. Syntax : BlitterNasty
  543.  
  544.   This will set the BlitterNasty hardware register bit, which means that
  545. the Blitter has complete priority over the CPU. This function returns
  546. the old status.
  547.  
  548. *NOTE* In order for this to be effective, place this command in a loop
  549. after a VWait.
  550.  
  551.  
  552. Function : FuncLibVersion
  553. ------------------------------------------------------------------------------
  554. Mode   : N/A
  555. Syntax : N/A
  556.  
  557.   This command does nothing (except return 0). Press HELP on the command
  558. name for your current version (v1.36 or higher only)
  559.  
  560.  
  561. ==============================================================================
  562.                               VERSION HISTORY
  563. ==============================================================================
  564.  
  565. Version    0.9
  566. ~~~~~~~~~~~
  567. Internal release. BLoad/BSave/Reserve/Erase only... (Blitz Statements)
  568.  
  569. Version 1.0
  570. ~~~~~~~~~~~
  571. First public release. Many new commands... (Assembly)
  572.  
  573. Version 1.1
  574. ~~~~~~~~~~~
  575. Bundled in RIBlitzlibsv3.1.lha on Aminet. Also published on BUM7
  576. Added a few extra commands
  577.  
  578. Version 1.2
  579. ~~~~~~~~~~~
  580. Changed CacheOff to CachesOff. Now supports a bitmask for disabling
  581. any caches you want. CachesOn added - so you can turn them back on.
  582. Don't know why it wasn't in before - I guess it didn't work before...
  583.  
  584. Version 1.3
  585. ~~~~~~~~~~~
  586. Fixed bug in CopyByte/CopyWord/CopyLong - using DBRA so only 65535
  587. copies could be done. (Thanks Steve Mc)
  588.  
  589. Version 1.31
  590. ~~~~~~~~~~~~
  591. Fixed memory drain in FileSize (DosObject not freed)
  592.   Reported by Ott Aloe from 'The Farm' - Thanks Ott
  593.  
  594. Version 1.32
  595. ~~~~~~~~~~~~
  596. Added CD command to change current directory. (Request by Ott)
  597.  
  598. Version 1.33
  599. ~~~~~~~~~~~~
  600. Fixed bug I introduced in FileSize (was freeing DosObject before
  601. getting the length of file)
  602.  
  603. Version 1.34
  604. ~~~~~~~~~~~~
  605. Added single parameter option to Reserve (only length). Returns
  606. bank number else -1.
  607.  
  608. Version 1.35
  609. ~~~~~~~~~~~~
  610. Added single parameter option to BLoad (only filename). Returns
  611. bank number else -1.
  612.  
  613. Added NOTE to BlitterNasty docs because copperlist would trash
  614. the bit every 50th.
  615.  
  616. Version 1.36
  617. ~~~~~~~~~~~~
  618. Fixed stupid bug in BLoad. Meant that FNSLoad/ILBMLoad would not
  619. work.
  620. Added FuncLibVersion to display current lib version
  621.